<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>flat_stream</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Beast">
<link rel="up" href="../ref.html" title="This Page Intentionally Left Blank 2/2">
<link rel="prev" href="boost__beast__flat_static_buffer_base/size.html" title="flat_static_buffer_base::size">
<link rel="next" href="boost__beast__flat_stream/async_read_some.html" title="flat_stream::async_read_some">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost__beast__flat_static_buffer_base/size.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ref.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost__beast__flat_stream/async_read_some.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="beast.ref.boost__beast__flat_stream"></a><a class="link" href="boost__beast__flat_stream.html" title="flat_stream">flat_stream</a>
</h4></div></div></div>
<p>
        Stream wrapper to improve ssl::stream write performance.
      </p>
<h5>
<a name="beast.ref.boost__beast__flat_stream.h0"></a>
        <span class="phrase"><a name="beast.ref.boost__beast__flat_stream.synopsis"></a></span><a class="link" href="boost__beast__flat_stream.html#beast.ref.boost__beast__flat_stream.synopsis">Synopsis</a>
      </h5>
<p>
        Defined in header <code class="literal">&lt;<a href="../../../../../../boost/beast/experimental/core/flat_stream.hpp" target="_top">boost/beast/experimental/core/flat_stream.hpp</a>&gt;</code>
      </p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span>
    <span class="keyword">class</span> <span class="identifier">NextLayer</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">flat_stream</span>
</pre>
<h5>
<a name="beast.ref.boost__beast__flat_stream.h1"></a>
        <span class="phrase"><a name="beast.ref.boost__beast__flat_stream.types"></a></span><a class="link" href="boost__beast__flat_stream.html#beast.ref.boost__beast__flat_stream.types">Types</a>
      </h5>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Name
                </p>
              </th>
<th>
                <p>
                  Description
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a class="link" href="boost__beast__flat_stream/executor_type.html" title="flat_stream::executor_type"><span class="bold"><strong>executor_type</strong></span></a>
                </p>
              </td>
<td>
                <p>
                  The type of the executor associated with the object.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="boost__beast__flat_stream/lowest_layer_type.html" title="flat_stream::lowest_layer_type"><span class="bold"><strong>lowest_layer_type</strong></span></a>
                </p>
              </td>
<td>
                <p>
                  The type of the lowest layer.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="boost__beast__flat_stream/next_layer_type.html" title="flat_stream::next_layer_type"><span class="bold"><strong>next_layer_type</strong></span></a>
                </p>
              </td>
<td>
                <p>
                  The type of the next layer.
                </p>
              </td>
</tr>
</tbody>
</table></div>
<h5>
<a name="beast.ref.boost__beast__flat_stream.h2"></a>
        <span class="phrase"><a name="beast.ref.boost__beast__flat_stream.member_functions"></a></span><a class="link" href="boost__beast__flat_stream.html#beast.ref.boost__beast__flat_stream.member_functions">Member Functions</a>
      </h5>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Name
                </p>
              </th>
<th>
                <p>
                  Description
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a class="link" href="boost__beast__flat_stream/async_read_some.html" title="flat_stream::async_read_some"><span class="bold"><strong>async_read_some</strong></span></a>
                </p>
              </td>
<td>
                <p>
                  Start an asynchronous read.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="boost__beast__flat_stream/async_write_some.html" title="flat_stream::async_write_some"><span class="bold"><strong>async_write_some</strong></span></a>
                </p>
              </td>
<td>
                <p>
                  Start an asynchronous write.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="boost__beast__flat_stream/flat_stream.html" title="flat_stream::flat_stream"><span class="bold"><strong>flat_stream</strong></span></a>
                </p>
              </td>
<td>
                <p>
                  Constructor.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="boost__beast__flat_stream/get_executor.html" title="flat_stream::get_executor"><span class="bold"><strong>get_executor</strong></span></a>
                </p>
              </td>
<td>
                <p>
                  Get the executor associated with the object.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="boost__beast__flat_stream/lowest_layer.html" title="flat_stream::lowest_layer"><span class="bold"><strong>lowest_layer</strong></span></a>
                </p>
              </td>
<td>
                <p>
                  Get a reference to the lowest layer.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="boost__beast__flat_stream/next_layer.html" title="flat_stream::next_layer"><span class="bold"><strong>next_layer</strong></span></a>
                </p>
              </td>
<td>
                <p>
                  Get a reference to the next layer.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="boost__beast__flat_stream/operator_eq_.html" title="flat_stream::operator="><span class="bold"><strong>operator=</strong></span></a>
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="boost__beast__flat_stream/read_some.html" title="flat_stream::read_some"><span class="bold"><strong>read_some</strong></span></a>
                </p>
              </td>
<td>
                <p>
                  Read some data from the stream.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="boost__beast__flat_stream/write_some.html" title="flat_stream::write_some"><span class="bold"><strong>write_some</strong></span></a>
                </p>
              </td>
<td>
                <p>
                  Write some data to the stream.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="boost__beast__flat_stream/flat_stream_dtor_.html" title="flat_stream::~flat_stream"><span class="bold"><strong>~flat_stream</strong></span></a>
                </p>
              </td>
<td>
                <p>
                  Destructor.
                </p>
              </td>
</tr>
</tbody>
</table></div>
<h5>
<a name="beast.ref.boost__beast__flat_stream.h3"></a>
        <span class="phrase"><a name="beast.ref.boost__beast__flat_stream.description"></a></span><a class="link" href="boost__beast__flat_stream.html#beast.ref.boost__beast__flat_stream.description">Description</a>
      </h5>
<p>
        This wrapper flattens writes for buffer sequences having length greater than
        1 and total size below a predefined amount, using a dynamic memory allocation.
        It is primarily designed to overcome a performance limitation of the current
        version of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span></code>,
        which does not use OpenSSL's scatter/gather interface for its low-level read
        some and write some operations.
      </p>
<h5>
<a name="beast.ref.boost__beast__flat_stream.h4"></a>
        <span class="phrase"><a name="beast.ref.boost__beast__flat_stream.example"></a></span><a class="link" href="boost__beast__flat_stream.html#beast.ref.boost__beast__flat_stream.example">Example</a>
      </h5>
<p>
        To use the <a class="link" href="boost__beast__flat_stream.html" title="flat_stream"><code class="computeroutput"><span class="identifier">flat_stream</span></code></a> template with SSL streams,
        declare a variable of the correct type. Parameters passed to the constructor
        will be forwarded to the next layer's constructor:
      </p>
<pre class="programlisting"><span class="identifier">flat_stream</span><span class="special">&lt;</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span><span class="special">&lt;</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">&gt;&gt;</span> <span class="identifier">fs</span><span class="special">{</span><span class="identifier">ioc</span><span class="special">,</span> <span class="identifier">ctx</span><span class="special">};</span>
</pre>
<p>
        Alternatively you can write
      </p>
<pre class="programlisting"><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span><span class="special">&lt;</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">&gt;</span> <span class="identifier">ss</span><span class="special">{</span><span class="identifier">ioc</span><span class="special">,</span> <span class="identifier">ctx</span><span class="special">};</span>
<span class="identifier">flat_stream</span><span class="special">&lt;</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span><span class="special">&lt;</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">&gt;&amp;&gt;</span> <span class="identifier">fs</span><span class="special">{</span><span class="identifier">ss</span><span class="special">};</span>
</pre>
<p>
        The resulting stream may be passed to any stream algorithms which operate
        on synchronous or asynchronous read or write streams, examples include:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">read</span></code>, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">async_read</span></code>
          </li>
<li class="listitem">
            <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">write</span></code>, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">async_write</span></code>
          </li>
<li class="listitem">
            <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">read_until</span></code>, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">async_read_until</span></code>
          </li>
</ul></div>
<p>
        The stream may also be used as a template parameter in other stream wrappers,
        such as for websocket:
      </p>
<pre class="programlisting"><span class="identifier">websocket</span><span class="special">::</span><span class="identifier">stream</span><span class="special">&lt;</span><span class="identifier">flat_stream</span><span class="special">&lt;</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span><span class="special">&lt;</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">&gt;&gt;&gt;</span> <span class="identifier">ws</span><span class="special">{</span><span class="identifier">ioc</span><span class="special">,</span> <span class="identifier">ctx</span><span class="special">};</span>
</pre>
<h5>
<a name="beast.ref.boost__beast__flat_stream.h5"></a>
        <span class="phrase"><a name="beast.ref.boost__beast__flat_stream.template_parameters"></a></span><a class="link" href="boost__beast__flat_stream.html#beast.ref.boost__beast__flat_stream.template_parameters">Template
        Parameters</a>
      </h5>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Type
                </p>
              </th>
<th>
                <p>
                  Description
                </p>
              </th>
</tr></thead>
<tbody><tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">NextLayer</span></code>
                </p>
              </td>
<td>
                <p>
                  The type representing the next layer, to which data will be read
                  and written during operations. For synchronous operations, the
                  type must support the SyncStream concept. For asynchronous operations,
                  the type must support the AsyncStream concept. This type will usually
                  be some variation of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span></code>.
                </p>
              </td>
</tr></tbody>
</table></div>
<h5>
<a name="beast.ref.boost__beast__flat_stream.h6"></a>
        <span class="phrase"><a name="beast.ref.boost__beast__flat_stream.concepts"></a></span><a class="link" href="boost__beast__flat_stream.html#beast.ref.boost__beast__flat_stream.concepts">Concepts</a>
      </h5>
<p>
        <span class="bold"><strong>AsyncStream</strong></span> <span class="bold"><strong>SyncStream</strong></span>
      </p>
<h5>
<a name="beast.ref.boost__beast__flat_stream.h7"></a>
        <span class="phrase"><a name="beast.ref.boost__beast__flat_stream.see_also"></a></span><a class="link" href="boost__beast__flat_stream.html#beast.ref.boost__beast__flat_stream.see_also">See
        Also</a>
      </h5>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            <a href="https://github.com/boostorg/beast/issues/1108" target="_top">https://github.com/boostorg/beast/issues/1108</a>
          </li>
<li class="listitem">
            <a href="https://github.com/boostorg/asio/issues/100" target="_top">https://github.com/boostorg/asio/issues/100</a>
          </li>
<li class="listitem">
            <a href="https://stackoverflow.com/questions/38198638/openssl-ssl-write-from-multiple-buffers-ssl-writev" target="_top">https://stackoverflow.com/questions/38198638/openssl-ssl-write-from-multiple-buffers-ssl-writev</a>
          </li>
<li class="listitem">
            <a href="https://stackoverflow.com/questions/50026167/performance-drop-on-port-from-beast-1-0-0-b66-to-boost-1-67-0-beast" target="_top">https://stackoverflow.com/questions/50026167/performance-drop-on-port-from-beast-1-0-0-b66-to-boost-1-67-0-beast</a>
          </li>
</ul></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2016, 2017 Vinnie Falco<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost__beast__flat_static_buffer_base/size.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ref.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost__beast__flat_stream/async_read_some.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
